home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / langs / iconv8_s.arc / DOCS.ARC / IPD137.DOC < prev    next >
Encoding:
Text File  |  1990-04-03  |  7.6 KB  |  331 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.        Source Code for Version 8 of Icon for the Atari ST
  8.  
  9.                         Ralph E. Griswold
  10.                           April 2, 1990
  11.  
  12.  
  13.  
  14. Introduction
  15.  
  16.    Version 8 of Icon compiles using the Lattice 68000 C compiler,
  17. Version 6.04.  There are hooks for the Mark Williams C compiler,
  18. but not all the configuration information is in place yet.
  19.  
  20.    The enclosed distribution diskette contains source code for
  21. Version 8 of the Icon programming language [1,2], configured to
  22. compile on the Atari ST. It also contains documentation, some
  23. tools to assist in the implementation - ASH, a command-line pro-
  24. cessor and arc.prg, a program for extracting files from ARC for-
  25. mat.
  26.  
  27.    If you do not have arc.prg installed already, copy it from the
  28. distribution diskette to the folder in which you plan to work.
  29.  
  30.    If you do not have ASH installed or are not familiar with its
  31. use, copy ash.prg and ash.ini from the distribution diskette to
  32. the folder in which you plan to work. Read ash.doc and ash.hlp on
  33. the distribution diskette for more information.  Start up ASH and
  34. proceed.
  35.  
  36.    Printed documentation comes with diskettes provided by the
  37. Icon Project at the University of Arizona. If you got your Icon
  38. diskette from another source without printed copies of the docu-
  39. mentation, dearchive the documents. Assuming the distribution
  40. diskette is in drive a:, do
  41.  
  42.         arc x a:docs.arc
  43.  
  44. Then print the files that are produced.
  45.  
  46.    In order to unload and compile Icon, you need plenty of disk
  47. space, and the resources to create at least seven new folders.
  48.  
  49. Unloading_Icon_Source_Code
  50.  
  51.    Create a folder in which you want Icon source code to reside
  52. (which we call icon here).
  53.  
  54.    Make four folders in icon for the source code:
  55.  
  56.         mkdir h
  57.         mkdir icont
  58.         mkdir iconx
  59.         mkdir common
  60.  
  61.  
  62.  
  63.  
  64. IPD137                        - 1 -                 April 2, 1990
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.    To unload the source code, place the Icon distribution
  74. diskette in a disk drive (assumed to be a: here). Then
  75.  
  76.         cd h
  77.         arc x a:h.arc
  78.         cd ..\icont
  79.         arc x a:icont.arc
  80.         cd ..\iconx
  81.         arc x a:iconx.arc
  82.         cd ..\common
  83.         arc x a:common.arc
  84.         cd ..
  85.  
  86.  
  87. Compiling_Icon
  88.  
  89.    Your PATH variable should be set so that the Lattice compiler
  90. can be found.  For example, if the compiler is in d:\lattice, the
  91. command
  92.  
  93.         set PATH="d:\lattice:$PATH"
  94.  
  95. can be used. Better yet, include this PATH in your ash.ini file,
  96. so that subshells can find the compiler.
  97.  
  98.    Scripts are provided to carry out the compilation. First com-
  99. pile the programs in common, which are used in building the two
  100. executable parts of Icon:
  101.  
  102.         cd icont
  103.         makecomn
  104.         cd ..
  105.  
  106.  
  107.    Then build icont, which translates and links Icon programs:
  108.  
  109.         cd icont
  110.         makeicnt
  111.         mv icont.prg ..
  112.         cd ..
  113.  
  114.  
  115.    Next, build iconx, the Icon executor:
  116.  
  117.         cd iconx
  118.         makeicnx
  119.         mv iconx.prg ..
  120.         cd ..
  121.  
  122.  
  123.    If all goes well, you should have a running version of Icon in
  124. your icon folder.  You may wish to move the two .prg files to a
  125. convenient place on your search path.
  126.  
  127.  
  128.  
  129.  
  130. IPD137                        - 2 -                 April 2, 1990
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. Testing_Icon
  140.  
  141.    To test Icon, create a folder tests in your icon folder and
  142. unload the test programs from the distribution diskette:
  143.  
  144.         mkdir tests
  145.         cd tests
  146.         arc x a:tests.arc
  147.  
  148.  
  149.    As a simple first test, try
  150.  
  151.         icont hello
  152.         iconx hello
  153.  
  154. You should get output that looks like this:
  155.  
  156.         Icon Version 8. March 25, 1990.
  157.         Atari ST (GEMDOS) Lattice C 3.04.02
  158.         Atari ST
  159.         co-expressions
  160.         environment variables
  161.         error trace back
  162.         expandable regions
  163.         external functions
  164.         keyboard functions
  165.         math functions
  166.         string invocation
  167.         system function
  168.  
  169.  
  170.    To perform more extensive testing, create two new folders in
  171. tests to hold ``standard'' and ``local'' test output:
  172.  
  173.         mkdir stand
  174.         mkdir local
  175.  
  176. Standard output is on the distribution diskette. To unload it,
  177.  
  178.         cd stand
  179.         arc x a:stand.arc
  180.         cd ..
  181.  
  182. Complete testing is time consuming. You may want to do only part
  183. of it, or do it in pieces. The script dtest.ash runs one test
  184. program and puts the output in local with a .out extension.  For
  185. example,
  186.  
  187.         dtest hello
  188.  
  189. runs hello.icn and puts the output in local\hello.out.
  190.  
  191.    If you want to do all the testing at once, use
  192.  
  193.  
  194.  
  195.  
  196. IPD137                        - 3 -                 April 2, 1990
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.         alltest
  206.  
  207. (and prepare to wait a while).
  208.  
  209.    To be sure Icon is running correctly, compare the output in
  210. stand to that in local.  There will be some differences, since
  211. some of the tests depend on the time, date, and environment.
  212. These differences should be obvious.  If you're ambitious, you
  213. may wish to write an Icon program to compare output files in the
  214. two directories and list and differences.  For a start, write a
  215. program that compares output files and simply reports if there
  216. are any differences.
  217.  
  218. Trouble_Shooting
  219.  
  220.    The most likely problem you may encounter is inadequate memory
  221. for iconx.  It reserves (via MNEED) 200,000 bytes of RAM for its
  222. allocated storage. If you do not have that much available, iconx
  223. terminates with a ``setblock failure''.
  224.  
  225.    If this happens, you may need to remove resources that are
  226. using memory, such as RAM disks. Alternatively, you can reduce
  227. MNEED (which is in iconx\rlocal.c).  If you reduce MNEED, you'll
  228. probably also have to reduce the sizes of Icon's allocated data
  229. regions.  This can be done using environment variables as
  230. described in [3].  For example, Icon's string and block regions
  231. normally are 65,000 bytes.  You can try small sizes to get
  232. started, such as
  233.  
  234.         set STRSIZE=10000
  235.         set HEAPSIZE=10000
  236.  
  237.  
  238.    It's also possible that most programs will have enough memory,
  239. but some won't.  For example, very large programs (like
  240. augment.icn in tests) may exceed the amount of memory available.
  241. This shows up as a run-time error during startup of iconx.  Set-
  242. ting environment variables may provide a work-around. Similarly,
  243. programs that create an unusually large number of co-expressions
  244. (like coexpr.icn in tests) may run out of memory during execu-
  245. tion. Again, taking space from one region and giving it to
  246. another may provide a work-around.
  247.  
  248.    If you find that Icon's default region sizes will not work for
  249. routine programs, you may wish to put appropriate alternative
  250. settings in ash.ini so that you don't have to set them manually
  251. every time you start up.
  252.  
  253. Technical_Notes
  254.  
  255.    The -x option to icont is disabled because it does not work
  256. properly. The system(s) function also does not work.
  257.  
  258.  
  259.  
  260.  
  261.  
  262. IPD137                        - 4 -                 April 2, 1990
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271. Acknowledgements
  272.  
  273.    The original modifications to adapt the Icon source code to
  274. the Atari ST were done by Rick Fonorow and Jerry Nowlin.  Charles
  275. Richmond did most of the subsequent work.
  276.  
  277. References
  278.  
  279.  
  280. 1.   R. E. Griswold and M. T. Griswold, The Icon Programming
  281.      Language, Prentice-Hall, Inc., Englewood Cliffs, NJ, second
  282.      edition, in press.
  283.  
  284. 2.   R. E. Griswold, Version 8 of Icon, The Univ. of Arizona
  285.      Tech. Rep. 90-1, 1990.
  286.  
  287. 3.   R. E. Griswold, Version 8 of Icon for the Atari ST, The
  288.      Univ. of Arizona Icon Project Document IPD136, 1990.
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328. IPD137                        - 5 -                 April 2, 1990
  329.  
  330.  
  331.